.\"
.\" Copyright (c) 2015-2020 Mindaugas Rasiukevicius <rmind at netbsd org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd May 13, 2020
.Dt libnpfkern 3
.Os
.Sh NAME
.Nm libnpfkern
.Nd standalone NPF packet filter (kernel component) as library
.Sh LIBRARY
.Lb libnpfkern
.Sh SYNOPSIS
.In net/npf.h
.In net/npfkern.h
.\" ---
.Ft int
.Fn npfk_sysinit "unsigned nworkers"
.Ft void
.Fn npfk_sysfini "void"
.Ft npf_t *
.Fn npfk_create "int flags" "const npf_mbufops_t *mbufops" \
"const npf_ifops_t *ifops" "void *arg"
.Ft int
.Fn npfk_load "npf_t *npf" "void *ref" "npf_error_t *err"
.Ft int
.Fn npfk_socket_load "npf_t *npf" "int sock"
.Ft void
.Fn npfk_gc "npf_t *npf"
.Ft void
.Fn npfk_destroy "npf_t *npf"
.Ft void
.Fn npfk_thread_register "npf_t *npf"
.Ft void
.Fn npfk_thread_unregister "npf_t *npf"
.Ft int
.Fn npfk_packet_handler "npf_t *npf" "struct mbuf **mp" \
"struct ifnet *ifp" "int di"
.Ft void
.Fn npfk_ifmap_attach "npf_t *npf" "struct ifnet *ifp"
.Ft void
.Fn npfk_ifmap_detach "npf_t *npf" "struct ifnet *ifp"
.Ft int
.Fn npfk_param_get "npf_t *npf" "const char *name" "int64_t *val"
.Ft int
.Fn npfk_param_set "npf_t *npf" "const char *name" "int64_t val"
.Ft void
.Fn npfk_stats "npf_t *npf" "uint64_t *buf"
.Ft void
.Fn npfk_stats_clear "npf_t *npf"
.\" -----
.Sh DESCRIPTION
The
.Nm
library provides an interface to kernel component of the NPF packet filter.
.\" -----
.Sh FUNCTIONS
.Bl -tag -width 4n
.\" ---
.It Fn npfk_sysinit "nworkers"
Initialize the NPF kernel component system.
This must be called before starting the use of
.Nm
library.
The
.Fa nworkers
parameter specifies how many worker threads should be spawned.
The workers perform such operations as connection expiration and destruction
amongst all the instances.
.Pp
Returns zero on success and the error number on failure.
.\" ---
.It Fn npfk_sysfini
Destroy any resources used by the
.Fm
library, e.g. stop and exit the worker threads.
This function must be called once finished using the component.
.\" ---
.It Fn npfk_create "flags" "mbufops" "ifops" "arg"
Construct and return a new instance of the NPF kernel component.
The parameter
.Fa flags
should be 0 or
.Dv NPF_NO_GC .
The
.Dv NPF_NO_GC
flag disables garbage collection of connections and other objects.
.Pp
The parameters
.Fa mbufops
and
.Fa ifops
specify the operation vectors, that is, structures containing the set of
functions required to operate a network buffer (mbuf) or a network interface.
This functions abstract the real representation and shall be provided by
the caller.
.Pp
The
.Fa arg
parameter can be used to associate an arbitrary user context with an NPF
instance, so that this value could later be obtained by the functions in
the operation vectors.
.Pp
Returns a reference (pointer) to the instance on success and
.Dv NULL
on failure.
.\" ---
.It Fn npfk_gc "npf"
Perform the garbage collection of connection and/or any other objects
related to the specified NPF instance.
This routine should only be used if the instance was created with
.Dv NPF_NO_GC
flag.
.\" ---
.It Fn npfk_destroy "npf"
Destroy the instance of the NPF kernel component, freeing all resources
used by it.
.\" ---
.It Fn npfk_load "npf" "ref" "err"
Load a new configuration into the NPF instance.
The new configuration is specified by the
.Fa ref
parameter.
It is a reference to the configuration built by the
.Fn npf_config_build
function from the
.Xr libnpf 3
library.
.Pp
Returns zero on success and error number on failure.
The configuration structure referenced by
.Fa ref
will be left unmodified.
In a case of failure, additionally returns extra information in a
structure specified by the
.Fa err
parameter.
.\" ---
.It Fn npfk_socket_load "npf" "sock"
Load a new configuration into the NPF instance.
The new configuration should be passed through a socket, specified by the
.Fa sock
parameter.
It should be sent using the
.Fn npf_config_submit
function (with file descriptor being a socket) from the
.Xr libnpf 3
library.
Returns zero on success and -1 on failure.
.\" ---
.It Fn npfk_thread_register "npf"
Register a "processing context" i.e. a thread which will perform the
.Fn npfk_packet_handler
calls.
All threads processing packets (invoking the handler) must register;
all registered threads must also remove themselves from the register
using before exit using the
.Fa npfk_thread_unregister
routine.
Failure to register may result in undefined behaviour.
.\" ---
.It Fn npfk_thread_unregister "npf"
Remove the thread from the register of threads which process the packets.
.\" ---
.It Fn npfk_packet_handler "npf" "mp" "ifp" "di"
Inspect the packet, matching and processing it against the configuration
loaded in the specified NPF instance.
This is the main routine performing packet filtering (as well as any other
operations).
.Pp
The packet is specified by the
.Fa mp
parameter.
The NPF instance may destroy the packet and set this parameter to
.Dv NULL .
This is done on block, but may also be done on other operations (e.g.
if the rule procedure decides to consume the packet).
The network interface packet is passing-through is specified by the
.Fa ifp
parameter.
The packet direction is specified by the
.Fa di
parameter and may be either
.Dv PFIL_IN
or
.Dv PFIL_OUT .
.Pp
This function returns zero if the packet was "passed" and error number
otherwise.
A regular "block" is indicated by the
.Dv ENETUNREACH
error number.
.\" ---
.It Fn npfk_ifmap_attach "npf" "ifp"
Attach the virtual network interface to the NPF instance.
This indicates that the packets on this interface shall be processed.
.It Fn npfk_ifmap_detach "npf" "ifp"
Detach the virtual network interface from the NPF instance.
.\" ---
.It Fn npfk_param_get "npf" "name" "valp"
Get the parameter value of the given NPF instance.
On success, the function returns zero and the parameter value stored in
.Fa valp .
On failure, if the parameter does not exist, the function returns
.Dv ENOENT .
.\" ---
.It Fn npfk_param_set "npf" "name" "val"
Set the parameter vale for the given NPF instance.
Returns zero on success or
.Dv ENOENT
if the parameter does not exist.
.\" ---
.It Fn npfk_stats "npf" "buf"
Get the statistics of the NPF instance into the buffer specified by the
.Fa buf
parameter.
.Pp
The buffer should be an array of
.Dv uint64_t
integers having at least
.Dv NPF_STATS_COUNT
number of elements (or
.Dv NPF_STATS_SIZE
in bytes).
.\" ---
.It Fn npfk_stats_clear "npf"
Clear (by resetting to zero) the statistics of the given NPF instance.
.\" ---
.El
.\" -----
.Sh SEE ALSO
.Xr libnpf 3 ,
.Xr bpf 4 ,
.Xr bpfjit 4 ,
.Xr npf.conf 5 ,
.Xr pcap-filter 7 ,
.Xr npfctl 8
.Sh HISTORY
NPF
first appeared in
.Nx 6.0 .
.Sh AUTHORS
NPF
was designed and implemented by
.An Mindaugas Rasiukevicius .
